7.5.2 Date Functions

The t N (calc-now) [now] command pushes the current date and time on the stack as a date form. The time is reported in terms of the specified time zone; with no numeric prefix argument, t N reports for the current time zone.

The t P (calc-date-part) command extracts one part of a date form. The prefix argument specifies the part; with no argument, this command prompts for a part code from 1 to 9. The various part codes are described in the following paragraphs.

The M-1 t P [year] function extracts the year number from a date form as an integer, e.g., 1991. This and the following functions will also accept a real number for an argument, which is interpreted as a standard Calc day number. Note that this function will never return zero, since the year 1 BC immediately precedes the year 1 AD.

The M-2 t P [month] function extracts the month number from a date form as an integer in the range 1 to 12.

The M-3 t P [day] function extracts the day number from a date form as an integer in the range 1 to 31.

The M-4 t P [hour] function extracts the hour from a date form as an integer in the range 0 (midnight) to 23. Note that 24-hour time is always used. This returns zero for a pure date form. This function (and the following two) also accept HMS forms as input.

The M-5 t P [minute] function extracts the minute from a date form as an integer in the range 0 to 59.

The M-6 t P [second] function extracts the second from a date form. If the current precision is 12 or less, the result is an integer in the range 0 to 59. For higher precision, the result may instead be a floating-point number.

The M-7 t P [weekday] function extracts the weekday number from a date form as an integer in the range 0 (Sunday) to 6 (Saturday).

The M-8 t P [yearday] function extracts the day-of-year number from a date form as an integer in the range 1 (January 1) to 366 (December 31 of a leap year).

The M-9 t P [time] function extracts the time portion of a date form as an HMS form. This returns ‘0@ 0' 0"’ for a pure date form.

The t M (calc-new-month) [newmonth] command computes a new date form that represents the first day of the month specified by the input date. The result is always a pure date form; only the year and month numbers of the input are retained. With a numeric prefix argument n in the range from 1 to 31, t M computes the nth day of the month. (If n is greater than the actual number of days in the month, or if n is zero, the last day of the month is used.)

The t Y (calc-new-year) [newyear] command computes a new pure date form that represents the first day of the year specified by the input. The month, day, and time of the input date form are lost. With a numeric prefix argument n in the range from 1 to 366, t Y computes the nth day of the year (366 is treated as 365 in non-leap years). A prefix argument of 0 computes the last day of the year (December 31). A negative prefix argument from -1 to -12 computes the first day of the nth month of the year.

The t W (calc-new-week) [newweek] command computes a new pure date form that represents the Sunday on or before the input date. With a numeric prefix argument, it can be made to use any day of the week as the starting day; the argument must be in the range from 0 (Sunday) to 6 (Saturday). This function always subtracts between 0 and 6 days from the input date.

Here’s an example use of newweek: Find the date of the next Wednesday after a given date. Using M-3 t W or ‘newweek(d, 3)’ will give you the preceding Wednesday, so ‘newweek(d+7, 3)’ will give you the following Wednesday. A further look at the definition of newweek shows that if the input date is itself a Wednesday, this formula will return the Wednesday one week in the future. An exercise for the reader is to modify this formula to yield the same day if the input is already a Wednesday. Another interesting exercise is to preserve the time-of-day portion of the input (newweek resets the time to midnight; hint: how can newweek be defined in terms of the weekday function?).

The ‘pwday(date)’ function (not on any key) computes the day-of-month number of the Sunday on or before date. With two arguments, ‘pwday(date, day)’ computes the day number of the Sunday on or before day number day of the month specified by date. The day must be in the range from 7 to 31; if the day number is greater than the actual number of days in the month, the true number of days is used instead. Thus ‘pwday(date, 7)’ finds the first Sunday of the month, and ‘pwday(date, 31)’ finds the last Sunday of the month. With a third weekday argument, pwday can be made to look for any day of the week instead of Sunday.

The t I (calc-inc-month) [incmonth] command increases a date form by one month, or by an arbitrary number of months specified by a numeric prefix argument. The time portion, if any, of the date form stays the same. The day also stays the same, except that if the new month has fewer days the day number may be reduced to lie in the valid range. For example, ‘incmonth(<Jan 31, 1991>)’ produces ‘<Feb 28, 1991>’. Because of this, t I t I and M-2 t I do not always give the same results (‘<Mar 28, 1991>’ versus ‘<Mar 31, 1991>’ in this case).

The ‘incyear(date, step)’ function increases a date form by the specified number of years, which may be any positive or negative integer. Note that ‘incyear(d, n)’ is equivalent to ‘incmonth(d, 12*n)’, but these do not have simple equivalents in terms of day arithmetic because months and years have varying lengths. If the step argument is omitted, 1 year is assumed. There is no keyboard command for this function; use C-u 12 t I instead.

There is no newday function at all because F [floor] serves this purpose. Similarly, instead of incday and incweek simply use ‘d + n’ or ‘d + 7 n’.

See Basic Arithmetic, for the f ] [incr] command which can adjust a date/time form by a certain number of seconds.